Skip to content

docs: README landing page with a produce/verify demo GIF and a CI-verified quickstart - #55

Merged
open-coder-ai-org merged 3 commits into
mainfrom
docs/readme-landing
Sep 9, 2026
Merged

docs: README landing page with a produce/verify demo GIF and a CI-verified quickstart#55
open-coder-ai-org merged 3 commits into
mainfrom
docs/readme-landing

Conversation

@open-coder-ai-org

@open-coder-ai-org open-coder-ai-org commented Sep 8, 2026

Copy link
Copy Markdown
Collaborator

What

Refreshes the README's landing section per the shared README-refresh standard (org-plan #187,
epic #183): a centered header (name, one-line pitch, badges on one line), a rendered
context-report produce/verify demo GIF (docs/assets/demo.tapedocs/assets/demo.gif,
146 KB) inserted after the badges, the quickstart replaced with a self-contained block whose
JSON rows and verify output are real context-report output (verified reproducible — running
the extracted block in a fresh mktemp -d yields byte-identical inputHash values to what's in
the README), "Who it's for" reformatted as a table, "Every model you can reach" folded into a
provider table inside "Two models, not one", a new Supported agents table (reachability/cost
/fault per target, from payloads-v0.1.json and fault.py's documented-oracle coverage), and
the family table replaced with the shared, byte-identical version. Word count excluding tables
and fenced code: 1,012.

Also adds:

  • tools/quickstart_block.py (stdlib) + tests/test_quickstart_block.py, and a quickstart CI
    job that extracts the README's first fenced bash block and runs it in a fresh temp dir —
    proving the README's own quick start actually works. The test suite proves the extractor fails
    a broken block (bash -e exits 1); I also confirmed this by hand against the real block (exit 0)
    and a deliberately broken one (exit 1).
  • .github/workflows/render-demo.yml, dispatch-only, to reproduce the GIF; it never commits to
    main. The vhs binary download is checksum-verified (sha256sum -c against the release's own
    checksums.txt) rather than trusted blind.
  • docs/cli.md: the run/compare explanation (manifest schema, --dry-run/--n/--resume)
    and the "Every model you can reach" prose that the old quickstart carried inline, moved
    verbatim rather than deleted, linked from both places in the README they used to live.
  • A CHANGELOG [Unreleased] → Docs entry.

Deviations

  • No logo file exists in this repo and none was requested by the brief, so the centered header
    stays text-only rather than adding a placeholder image.
  • Badges: added PyPI (img.shields.io/pypi/v/context-report); no "Best Practices" badge exists
    today so none was added ("where present" per the shared standard).
  • render-demo.yml uses the plain VHS binary (checksum-pinned) instead of
    charmbracelet/vhs-action: this session had no way to fetch or verify a real commit SHA for
    that action (GitHub API access to repos outside this session's scope was unavailable), and
    pinning an unverified SHA would violate the "verify before adding a dependency" rule.
    actions/upload-artifact reuses the SHA already pinned elsewhere in this repo's own workflows.
  • context-report produce's --kind plugin --subject ./my-plugin example reports reachability: FAILED for a real, honest reason (${CLAUDE_PLUGIN_ROOT} resolves relative to the cwd you run
    it from, so the hook is only reachable from the one cwd where that relative path still
    resolves) — kept as-is rather than switched to an absolute path, since it's real, reproducible
    output and echoes the README's own "Reachable is not the same as executable" finding. The tape
    and the README quickstart now run the identical two commands (produce then verify), so the
    GIF's punchline is a command a reader actually ran.

Definition of done

  • python -m ruff check . and python -m ruff format --check . clean
  • python -m pytest -q green (408 passed); new tests cover the extractor's ordinary and
    broken-input cases
  • Schema changes: n/a, no schema touched
  • chock check and chock sync --repo . --check: n/a, .agents/policies/ untouched

Claims

  • No row is described as re-derivable unless it actually recomputes from the subject plus
    its recorded configuration and carries an inputHash. Every row shown in this PR's README
    changes is real context-report output, not illustrative.

Copy link
Copy Markdown
Collaborator Author

The chock adoption is valid check is failing, but not because of this diff: the policies job's "Check out the framework" step (open-coder-ai/chock at the pinned v0.8.0) fails with

remote: Repository 'open-coder-ai-org/chock' is disabled.
remote: Please ask the owner to check their account.
fatal: unable to access 'https://github.com/open-coder-ai/chock/': The requested URL returned error: 403

This diff never touches .agents/policies/, .framework-ref, or the policies job — it's an
external outage on the chock repository itself (name-redirected to open-coder-ai-org/chock,
currently disabled), unrelated to anything in this PR. actions/checkout's own automatic retry
already hit this identically three times in the same job run, so it isn't a one-off network
flake. No fix exists on this side — it needs the chock repo re-enabled upstream. I don't have
access to open-coder-ai/chock or open-coder-ai-org from this session to investigate further.


Generated by Claude Code

docs/assets/demo.tape drives context-report produce and verify against
my-plugin, a two-file Claude Code plugin bundle, and renders
docs/assets/demo.gif (VHS, Catppuccin Mocha, per the shared README-refresh
recipe). Matches the README quickstart's own commands exactly.

Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Centered header (name, one-line pitch, badges reordered CI/PyPI/Python/
License/Scorecard/PRs, no logo file exists so none is added), the demo GIF
inserted after the badges, the quickstart replaced with a self-contained
block whose JSON rows and verify output are real context-report output,
"Who it's for" as a table, "Every model you can reach" folded into a
provider table inside "Two models, not one", a new Supported agents table,
and the family table replaced with the shared byte-identical version.

The run/compare explanation and the "Every model you can reach" prose that
used to sit inline move verbatim into docs/cli.md, linked from both places
they used to live.

Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
tools/quickstart_block.py extracts the first fenced bash block under the
README's quickstart heading, stdlib only; a new quickstart CI job installs
the package from this checkout and runs the extracted block in a fresh
mktemp dir. tests/test_quickstart_block.py proves the extractor fails a
broken block under bash -e. A dispatch-only render workflow reproduces
docs/assets/demo.gif from its tape as an uploaded artifact, checksum-
verifying the vhs binary download; main stays protected and never receives
an automated commit.

Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@open-coder-ai-org
open-coder-ai-org marked this pull request as ready for review September 9, 2026 00:15
@open-coder-ai-org
open-coder-ai-org merged commit 13fefd5 into main Sep 9, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants